home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / os2 / xdsn217.zip / DOC / samples.txt < prev    next >
Text File  |  1996-07-09  |  9KB  |  274 lines
  1. SAMPLES.TXT                      Copyright (c) 1994,96 xTech Ltd
  2. ----------------------------------------------------------------
  3.  
  4.                  Native XDS-x86 OS/2 Edition
  5.                  ---------------------------
  6.                      v2.17 (pre-release)
  7.  
  8.                        Sample Programs
  9.  
  10.  
  11. We assume here, that XDS was properly installed, the working
  12. directory was created and the 'xdssamp' script was invoked
  13. (See readme.1st).
  14.  
  15. All examples in this text are provided for OS/2 edition.
  16. See your readme.1st file for the information concerning
  17. your distribution.
  18.  
  19. The "samples" directory contains the following subdirectories
  20. and files:
  21.         simple   - simple samples
  22.         dhry     - dhrystone test (note: a single module dhrystone
  23.                    test is placed to the "simple" directory)
  24.                    See also "bench.txt".
  25.         nodes    - an Oberon-2 example, illustrating usage
  26.                    of Oberon run-time support.
  27.         mand     - Mandelbrodt Set explorer for Presentation Manager.
  28.                    Written in Modula-2.
  29.         cset     - provides an example of mixed project, which
  30.                    consists of Modula-2 and C units.
  31.                    IBM's C compiler used.
  32.         watcom   - provides an example of mixed project, which
  33.                    consists of Modula-2 and C units.
  34.                    WATCOM's C compiler used.
  35.         *.prj    - XDS project files for samples .
  36.  
  37. samples\simple
  38. --------------
  39.  
  40. All  the  samples  on this directory consists of the only module.
  41. Tests are written in Modula-2 and in Oberon-2. In these tests the
  42. specific features  of  Oberon-2 are not used.
  43.  
  44. The following tests are provided:
  45.         hello.mod       Hello, World       (Modula-2)
  46.         hello.ob2       Hello, World       (Oberon-2)
  47.  
  48.         hisdemo.mod     History demo       (Modula-2) (See hisdemo.prj)
  49.  
  50.         ackerman.ob2    Ackermann function (Oberon-2)
  51.  
  52.         exp.ob2         Calculate exponent (Oberon-2)
  53.         exp.mod         Calculate exponent (Modula-2)
  54.  
  55.         self.ob2        Print self text    (Oberon-2)
  56.  
  57.         sieve.ob2       Prime numbers      (Oberon-2)
  58.         sieve.mod       Prime numbers      (Modula-2)
  59.  
  60.         fact.mod        Factorial          (Modula-2)
  61.  
  62.         halt.mod        Termination        (Modula-2)
  63.         term.mod        Termination        (Modula-2)
  64.         except.mod      Exceptions         (Modula-2)
  65.  
  66.         dry.mod         Drystone benchmark (Modula-2)
  67.                         (single module)
  68.         dry.c           Drystone benchmark (C)
  69.  
  70.         whet.mod        Whetstone          (Modula-2)
  71.  
  72.         linnew.mod      LinPack benchmark  (Modula-2)
  73.         linnew.c        LinPack benchmark  (C)
  74.  
  75. The xc.red redirection file, that was created in your working
  76. directory. already contains paths to the SIMPLE directory.
  77. To get an executable program for a sample, invoke "xc" in the make
  78. mode, passing a name of a sample module (w/o path). For example:
  79.  
  80.         xc hello.mod =make
  81. or
  82.         xc hello.ob2 =make
  83.  
  84. After that run the program:
  85.  
  86.         hello
  87.  
  88. For "hisdemo" sample, use:
  89.  
  90.         xc hisdemo.mod =make +genhistory
  91.  
  92. To see the stack of procedure calls ("execution history") use
  93. his utility (C:\XDS\BIN\his.exe):
  94.  
  95.         his
  96.  
  97. It searches for "errinfo.xds" file and appropriate map file to
  98. produce the list of procedure calls. Every item of the list consists
  99. of a source file name, a line number and optionaly a procedure name.
  100.  
  101. dry.c/dry.mod and linnew.c/linnew.mod are C and Modula-2 sources
  102. of the same programs. Use them to compare the output code quality
  103. of XDS and your C compiler(s).
  104.  
  105.  
  106. samples\dhry
  107. ------------
  108.  
  109. The "dhry" directory contains two variants of well known Dhrystone
  110. test:
  111.         puredhry.mod
  112.         timedhry.mod
  113.  
  114. Both tests imports "dry1" and "dry2" libraries.
  115.  
  116. To prepare executable use PROJECT operation mode. The redirection
  117. file contains path to the project file "puredhry.prj".
  118.  
  119.         xc =p puredhry
  120.  
  121.  
  122. samples\findproc
  123. ----------------
  124.  
  125. This directory contains sources of a sample XDS IDE tool.
  126.  
  127.     findproc.mod   - Modula-2 source
  128.     readme.txt     - tool setup instructions
  129.  
  130. Use the following command to build the executable
  131.  
  132.     xc =p findproc
  133.  
  134.  
  135. samples\nodes
  136. -------------
  137.  
  138. The "nodes" subdirectory contains the following files, constituting
  139. the Oberon-2 program:
  140.  
  141.         Nodes.ob2       - definition of abstract Node class
  142.         Echo.ob2        - concrete Node extension
  143.         GenEcho.ob2     - concrete Node extension
  144.         Commands.ob2    - concrete Node extension
  145.         Types.ob2       - concrete Node extension
  146.         runme.ob2       - the top-level module
  147.  
  148. To build the program, type:
  149.  
  150.         xc =p nodes.prj
  151.  
  152. The  "Nodes" module defines an abstract object (Node). Objects of
  153. this  type  are  linked  in  the  list.  The  module "Nodes" also
  154. implement  the  command  monitor  ("Loop"  procedure). The "Loop"
  155. procedure  reads an input from keyboard and then passes the input
  156. to  the  current  node,  or  if  the  input  line starts from "."
  157. executes some standard action.
  158.  
  159. The  module  "runme"  imports  modules defining the extensions of
  160. type  Node  (concrete  classes),  inserts it in the list and then
  161. call "Nodes.Loop".
  162.  
  163. Nodes.Node extensions:
  164. ----------------------
  165.  
  166. "Echo"     - implements a node which prints its input to terminal.
  167.  
  168. "GenEcho"  - if the number N is specified in the input line
  169.              creates "N" examples of the "Echo" Node.
  170.  
  171. "Commands" - provides facilities to call commands (exported
  172.              parameterless procedures) in the form:
  173.                 ModuleName.ProcedureName
  174.              Also implements operations to enumerate all modules
  175.              in the program and all commands in the given module.
  176.  
  177. "Types"    - provides facilities to allocate an object by the
  178.              given name in the form:
  179.                 ModuleName.RecordTypeName
  180.  
  181.  
  182. Modules   "Types"   and   "Commands"  illustrates  the  using  of
  183. meta-language   facilities,   including  the  command  calls  and
  184. creating an object by its type name.
  185.  
  186. It is important to note, that the XDS does not support the
  187. dynamic  loading  of  the modules. You can use commands and types
  188. from the modules which are already linked in the program.
  189.  
  190.  
  191. samples\mand
  192. ------------
  193.  
  194. Mandelbrodt Set Explorer for Presentation Manager. The directory contains:
  195.  
  196.     mand.mod - Modula-2 source text
  197.     mand.res - binary resource file
  198.     mand.exe - pre-built executable
  199.     readme.txt - short description
  200.  
  201. To build the executable file. issue the following commands
  202. at the OS/2 command prompt:
  203.  
  204.     xc =p mand
  205.     rc <xds directory>\samples\mand\mand.res mand.exe
  206.  
  207. Controls:
  208.     - press left mouse button to magnify image two times
  209.       (right button - four times )
  210.     - after the window size is changed, use the Refresh
  211.       command to update it
  212.     - use the Copy command to copy the current image
  213.       to the Clipboard
  214.     - use Back and Forward commands to review already
  215.       built images
  216.  
  217.  
  218. samples\cset
  219. ------------
  220.  
  221. The directory contains:
  222.         cmain.c         - main module of the program (C)
  223.         m2test.def      - definition module
  224.         m2test.mod      - implementation module
  225.         m2test.h        - header file (manually written)
  226.         stdio.def       - interface to <stdio.h>
  227.         cset.tem        - template file
  228.  
  229. The sample shows how to write mixed project, i.e. projects written
  230. partially in C and partially in Modula or Oberon. To compile
  231. this test, the IBM's CSET should be properly installed.
  232. For such a project the CSET library should be used.
  233.  
  234. To build the program, run:
  235.  
  236.         xc cset =p
  237.  
  238. Take in attention that XDS compiler does not support _Optlink calling
  239. conventions yet. So you can not call from Modula-2/Oberon-2 directly
  240. those functions of standard CSET library which use such conventions.
  241. To call _Optlink C function you must provide an intermediate C function
  242. with _SysCall conventions.
  243.  
  244. samples\watcom
  245. --------------
  246.  
  247. The directory contains: